home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Special 25 / AMIGAplus Sonderheft 25 (2000)(Falke)(DE)(Track 1 of 4)[!].iso / Updates / PowerPC / chunkyppc / chunkyppc.docs < prev    next >
Text File  |  2000-05-16  |  14KB  |  415 lines
  1. The ChunkyPPC Library
  2. =====================
  3.  
  4. --- snip ---
  5.  
  6. Newsflash:
  7.  
  8. This is a major new version of chunkyppc.library.
  9.  
  10. Note: The new functions are ONLY supported if you use chunkyppc.library
  11. as library, using it with linkchunkyppc.lib does not support the new
  12. functions !!! I included the old version of the linkchunkyppc.lib though,
  13. it just does not cover the new functions of V3+. If you need V3+, use
  14. it as Shared Library.
  15.  
  16. Mainly i included some new functions on request from *Hyperion Software* !!!
  17.  
  18. Hyperion wanted a OpenScreen/CloseScreen interface which can handle:
  19.  
  20. - Open on a Screen
  21. - Open on a WB Window
  22. - Open on a PIP Window
  23. - Open on a Pubscreen
  24. - use ASL Requester, not rtgmaster
  25. - rtgmaster requester optionally
  26. - change screenmodes of a running program "on the fly" (without having
  27.   to quit the program)
  28. - automatically handle Chunky-Format Conversions
  29. - Support for all 16 Bit Formats, RGB15 and LUT8 needed
  30. - For AGA 8 Bit and HAM8 needed
  31. - LoadRGB32 Feature with included Color-Adaption for WB-Window
  32. - Doublebuffering (both AllocScreenBuffer and ScrollVPort) and
  33.   Triple Buffering Support
  34. - Support for Custom Hooks both on 68k and WarpUP
  35. - has to work on both 68k and PowerPC (WarpUP)
  36.  
  37. Note: AGA Mode claims to be 15 Bit, but is really 16 Bit :) Just always
  38. use PIXFMT_RGB15 for AGA in ChunkyInit :)
  39.  
  40. Note: Executables compiled for chunkyppc.library V3-V11 (which were internal
  41. releases anyways) don't work anymore on V11. This is V14. If you have a
  42. Beta V3-V9, don't give it to anyone, to avoid confusion. Only versions
  43. which should be given to other people are V14 or the old V2 ones. But
  44. nothing "in-between".
  45.  
  46. Note: Due to the special implementation of EGCS-WarpUP the ms.algo cannot
  47. be called directly with it. Use The CallChunkyCopy #define in the
  48. include instead. For other compilers you can just
  49.  
  50. #define CallChunkyCopy ms.algo
  51.  
  52. Since V3.0 chunkyppc.library supports these features.
  53.  
  54. There are the following new functions:
  55.  
  56. OpenGraphics
  57. ------------
  58.  
  59. a0 : Title (of the program)
  60. a1 : Mode_Screen structure
  61. d0 : override flag
  62.  
  63. This function opens a screenmode-requester and after this a screen/window.
  64. It uses the following env-variables:
  65.  
  66. <Title>/modeid:
  67.  
  68. if the override flag is *not* set, use this modeid, if the ENV Variable
  69. is set (and if not, open a screenmode requester). If the flag is set, always
  70. open a screenmode requester. So default a Screenmode can be used, once the
  71. user saved one, but the screenmode can in-game still be changed.
  72.  
  73. Since V5 there is (on request of Hyperion Software) a override mode == 2.
  74. If this is set, inside env:<Title> (and envarc:<Title>) there will be a
  75. small Screenmode Database. OpenGraphics() then checks, if a modeid file
  76. is already found in the directory, if this modeid file has the correct
  77. resolution. This way it is possible to maintain several different resolutions
  78. in one database, without the screenmode-requester popping up on every
  79. screen-width/height/depth change (the names of the files are modeid,
  80. modeid1, modeid2, ...). Up to 21 entries (modeid, modeid1, ..., modeid20)
  81. are supported, if more are entered, modeid20 is changed always).
  82.  
  83. <Title>/dbuf:
  84.  
  85. Use Doublebuffering
  86.  
  87. <Title>/oldstyle
  88.  
  89. If this is set, ScrollVPort will be used, else Triple Buffering using
  90. ScreenBuffers.
  91.  
  92. <Title>/wb
  93.  
  94. If this is set, a Workbench Window will be used, not a screen
  95.  
  96. <Title>/pip
  97.  
  98. If this is set, a Picture in Picture will be used using the Picasso96API.library.
  99. Note: Not all Graphics Boards Support this. Currently only P96 PIP is supported,
  100. not CGX. Maybe in the future...
  101.  
  102. <Title>/ham
  103.  
  104. Use HAM8 mode for AGA. If this is not set, 8 Bit mode is used for AGA.
  105.  
  106. <Title>/pipnoclear
  107.  
  108. If this is set to 1, the PIP won't be cleared when opened.
  109.  
  110. <Title>/rtgmaster
  111.  
  112. Use rtgmaster Screenmode Requester instead of ASL one. rtgmaster.library
  113. will only be opened when this option is set, so that rtgmaster.library
  114. does not need to be installed to be able to use chunkyppc.library.
  115.  
  116. <Title>/likecgx
  117.  
  118. If you want CGX-like WB Window Support for P96 (Faster, but Window Borders
  119. disappear). For CGX it is automatically set, as it is the only possible
  120. method for CGX to reach (at least for 16 Bit) WB Window Support, for P96
  121. it is optional.
  122.  
  123. Hyperion Software will support a GUI to set these ENV-Variables for their
  124. products, as they told me.
  125.  
  126. The Mode_Screen structure is a special structure containing information
  127. on the screen, like the Screen-Structure of Intuition or the RtgScreen
  128. structure of rtgmaster. It does not matter if you got it by OpenGraphics
  129. or constructed it yourselves. The Mode_Screen structure also gets the
  130. minimum/maximum Width/Height/Depth, so you should init these values before you
  131. call OpenGraphics.
  132.  
  133. If the video_screen element of Mode_Screen is !=0 this screen will be closed,
  134. and a new one will be opened ("on-the-fly-screen-change").
  135.  
  136. The important elements of Mode_Screen (like defined in clib/chunkyppc_protos.h):
  137.  
  138. video_screen: An Intuition Screen
  139. video_window: An Intuition Window
  140. bpr: Bytes Per Row
  141. mode: The ModeID
  142. SCREENWIDTH: Minimal Width/Actual Width
  143. SCREENHEIGHT: Minimal Height/Actual Height
  144. MAXWIDTH: Maximum Width
  145. MAXHEIGHT: Maximum Height
  146. MINDEPTH: Minimum Depth
  147. MAXDEPTH: Maximum Depth
  148. format: Video Format (using Cybergraphics constants)
  149. video_depth: BitsPerPixel
  150. screen: Buffer 0 Video RAM / Address BitPlane 0
  151. screenb: Buffer 1 Video RAM / Address Bitplane 1
  152. screenc: Buffer 2 Video RAM / Address Bitplane 2
  153. bufnum: Active Buffer number
  154. bitmapa-bitmapc: the Bitmaps
  155. thebitmap: Active Bitmap
  156. numbuffers: Number of Buffers (ScrollVPort only 2, no DBuffering only 1)
  157. algo: Function-pointer to Chunky-Copy Algorithm
  158.  
  159. CloseGraphics
  160. -------------
  161.  
  162. a0: Mode_Screen structure
  163. d0: shutdownlibs Flag
  164.  
  165. This closes the Screen/Window again (and all other stuff... :) )
  166.  
  167. If shutdownlibs is set, the libraries used will also be closed.
  168. If not they will not be closed.
  169.  
  170. LoadColors
  171. ----------
  172.  
  173. This is basically the same like LoadRGB32 of graphics.library or
  174. LoadRGBRtg of rtgmaster. Set the colors of a 8 Bit Screen. Does nothing
  175. for a 15/16 Bit Screen.
  176.  
  177. a0: Mode_Screen structure
  178. a1: Color-array like for LoadRGB32/LoadRGBRtg
  179.  
  180. DoubleBuffer
  181. ------------
  182.  
  183. a0: Mode_Screen structure
  184.  
  185. Causes Double/Triplebuffering (depending on value of env:<Title>/oldstyle
  186. and env:<Title>/dbuf). Note WB Window and PIP Modes are single buffered.
  187. For Single-Buffered this does not do anything. For Triplebuffering it
  188. switches buffers in the sequence (when the screen is just opened buffer
  189. 0 is always active !!!) <0 is active at startup>-1-2-0-1-2-0 or
  190. <0 is active at startup>-1-0-1-0...
  191.  
  192. ChunkyInit
  193. ----------
  194.  
  195. r4: Mode_Screen structure
  196. r5: srcformat
  197.  
  198. This initializes ms->algo with a PowerPC ChunkyCopy/c2p including Colorformat
  199. Conversion according to src and destination format (ms->format...).
  200.  
  201. ChunkyInit68k
  202. -------------
  203.  
  204. a0: Mode_Screen structure
  205. d0: srcformat
  206.  
  207. This time a 68k function, and initializes ms->algo with a 68k algorithm.
  208.  
  209. If ChunkyInit/ChunkyInit68k returns 0, this means the source and the
  210. destination formats are incompatible !!!
  211.  
  212. The following formats are compatible currently:
  213.  
  214. - for PowerPC all 8 Bit and 16 Bit formats, and RGB15 15 Bit Format
  215. - on 68k 8 Bit and all 15 Bit and 16 Bit formats, but 15/16 Bit only
  216.   if source and destination have identical formats (68k currently
  217.   does not support format conversion)
  218. - For AGA: On Workbench Window only 8 Bit, naturally
  219. - For AGA: HAM8 mode only on PowerPC
  220. - On Workbench Window: 15/16 Bit formats only supported for Picasso 96,
  221.   as WritePixelArray of CyberGraphX does not support a 15/16 Bit
  222.   Input Format. On a Screen it is supported also for CGX though.
  223.   If you want this on CGX too -> write the CGX authors about it.
  224.  
  225. The Chunky Algorithms
  226. ---------------------
  227.  
  228. 68k:
  229.  
  230. a0: Mode_Screen structure
  231. a1: dest
  232. a2: src
  233. d0: srcformat
  234. d1: hook68k
  235. d2: data
  236.  
  237. PPC:
  238.  
  239. r4: Mode_Screen structure
  240. r5: dest
  241. r6: src
  242. r7: srcformat
  243. r8: hook68k
  244. r9: data
  245.  
  246. This performs a fullscreen copy of "src" to "dest" performing all
  247. needed format conversion. srcformat is in CyberGraphics Synax
  248. (PIXFMT_RGB16 or such). src is a Video RAM Pointer for GFX Board (you
  249. have to take care yourselves, if that of buffer 0,1 or 2 has to be
  250. provided). For AGA it is a poin